Restful API接口规范参考

规范 API, RESTful, 规范 评论

本文根据网上一些热度较高的相关内容编写，梳理了一些个人认为比较实用的场景。

概要

REST(Representational State Transfer)：可重新表达的状态迁移，名词，+ful为形容词，形容的是一种web服务互相传递信息的一种风格，这里不做具体深入。

域名

RESTful API通常推荐使用域名形式进行调用。一些服务与服务之间的通信可能不会用域名，而是使用IP进行动态调度，目的是为了避免DNS服务器解析域名异常可能造成的影响。

版本

接口版本定义，一般在URI路径下标识版本号信息（v1/v2/v3…），如：

1
https://api.amaging.cn/v1

路径

路径即“终点”（endpoint），代表API的具体地址。所有路径使用名词复数，同时保持一种树形结构，以公司的组织结构为例：

授权

通常OPEN API需进行必要的功能授权，一般使用授权码（ApiKey，简称：ak）进行功能授权。如：

1
https://api.amaging.cn/v1/depts?ak=bKMi8NhColge1HNf

HTTP动作

常用HTTP动作

  • GET（SELECT）：取出资源（一项或多项）。
  • POST（CREATE）：创建资源。
  • PUT（UPDATE）：更新（完整）资源。
  • PATCH（UPDATE）：更新（部分）资源，实际使用中通常会与PUT合并。
  • DELETE（DELETE）：删除资源。

示例

  • GET /depts：获取所有部门
  • POST /depts：创建新部门
  • GET /depts/1：获取指定部门信息
  • PUT /depts/1：更新部门信息
  • DELETE /depts/1：删除部门
  • GET /depts/1/teams：获取指定部门下的所有团队
  • DELETE /depts/1/teams/4：删除指定团队

过滤条件

分页

  • ?limit=10：指定返回记录的数量，如：默认10，不合法或超过允许的最大值时返回错误信息。
  • ?offset=10：指定返回记录的开始位置，即偏移量，默认0。

排序

  • ?sort=-age：按年龄倒序，字段前加“-”代表降序，默认升序。
  • ?sort=-age,salary：按年龄倒序同时按薪水升序，组合排序条件用“,”隔开。

返回域

  • ?fields=userName,level,salary：支持自定义返回域的设置，可减少不必要的字段返回。

复杂查询

  • ?id=2&level=5：支持的查询条件参考各接口API，同时允许一定的URI冗余，如leaders?id=2与leaders/2等效。

范围查询

  • ?by=salary& gte=25000& lte=35000：by（以哪个属性过滤），gte（大于等于），lte（小于等于）支持指定条件的范围查询
  • ?by=salary,level& gte=25000,3& lte=35000,5：支持范围组合查询，查询条件与范围值顺序需要对应，以“,”隔开。

模糊查询

优先考虑使用正则表达式进行模糊查询条件支持，正则表达式模糊查询内容较多，这里不再细述。实际情况中，由于（关系型）数据库的限制，以及开发效率问题，模糊查询在RESTful API中使用得相对较少。

常用HTTP状态码

这里只列举一些常用状态码，更详细的状态码可参考：https://zh.wikipedia.org/wiki/HTTP%E7%8A%B6%E6%80%81%E7%A0%81

  • 200 OK – [GET]：服务器成功返回用户请求的数据。
  • 201 Created – [POST/PUT]：新建或修改数据成功。
  • 202 Accepted – [*]：表示一个请求已经进入后台排队（异步任务）。
  • 204 No Contented – [DELETE]：删除数据成功。
  • 400 Bad Request – [GET/POST/PUT]：请求参数错误，服务端未进行业务处理。
  • 401 Unauthorized – [*]：无权限访问（token或用户名密码错误）。
  • 403 Forbidden – [*]：访问被禁止（已通过401授权）。
  • 404 Not Found – [*]：不存在的路径或请求记录。
  • 500 Internal Server Error – [*]：服务内部错误。
  • 502 Bad Gateway – [*]：网关错误，由网关或代理服务器抛出。
  • 503 Service Unavailable – [*]：服务不可用，由容器抛出。

错误处理

对于服务端主动返回的异常（HTTP 4XX），直接向用户返回对应的错误信息，如：

1
2
3
{
	error: "Invalid api key."
}

返回结果

服务端向用户返回的结果需符合以下规范：

  • GET /collection：返回资源对象的列表。
  • GET /collection/resource：返回单个（或多个）符合条件的资源对象（列表）。
  • POST /collection：返回新生成的资源对象。
  • PUT /collection/resource：返回更新后的资源对象。
  • DELETE /collection/resource：返回空文档。

如果返回的资源对象为列表，提供统一格式的分页信息，如：

1
2
3
4
5
"paging": {
	"limit": 10,	//返回记录的数量
	"offset": 0,	//返回记录的开始位置
	"total": 998	//符合条件的记录总数量
}

Hypermedia API

提供必要的Hypermedia，链向其他API方法，便于用户不查接口文档，即可知道下一步需要如何调用接口。Link规范参考如下：

1
2
3
4
5
6
7
"link": {
	"rel": "https://api.amaging.cn/v1/depts/{id}",	// 下一个API链接
	"href": "https://api.amaging.cn/v1/depts",	// 当前API链接
	"method": "GET,POST,PUT",	// 当前API支持的方法
	"title": "List of departments",	// 当前API功能描述
	"type": "application/json"	// 当前API返回的数据类型
}

参考链接：

  1. http://www.ruanyifeng.com/blog/2014/05/restful_api.html
  2. https://www.jianshu.com/p/8ad6327b30b1

DuckyRain高级Java & 系统架构